<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Chapter 25. Zend_Locale</title>
<link rel="stylesheet" href="dbstyle.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.72.0">
<link rel="start" href="index.html" title="Programmer's Reference Guide">
<link rel="up" href="index.html" title="Programmer's Reference Guide">
<link rel="prev" href="zend.loader.pluginloader.html" title="24.2. Loading Plugins">
<link rel="next" href="zend.locale.functions.html" title="25.2. Using Zend_Locale">
<link rel="chapter" href="introduction.html" title="Chapter 1. Introduction to Zend Framework">
<link rel="chapter" href="zend.acl.html" title="Chapter 2. Zend_Acl">
<link rel="chapter" href="zend.auth.html" title="Chapter 3. Zend_Auth">
<link rel="chapter" href="zend.cache.html" title="Chapter 4. Zend_Cache">
<link rel="chapter" href="zend.config.html" title="Chapter 5. Zend_Config">
<link rel="chapter" href="zend.console.getopt.html" title="Chapter 6. Zend_Console_Getopt">
<link rel="chapter" href="zend.controller.html" title="Chapter 7. Zend_Controller">
<link rel="chapter" href="zend.currency.html" title="Chapter 8. Zend_Currency">
<link rel="chapter" href="zend.date.html" title="Chapter 9. Zend_Date">
<link rel="chapter" href="zend.db.html" title="Chapter 10. Zend_Db">
<link rel="chapter" href="zend.debug.html" title="Chapter 11. Zend_Debug">
<link rel="chapter" href="zend.dojo.html" title="Chapter 12. Zend_Dojo">
<link rel="chapter" href="zend.dom.html" title="Chapter 13. Zend_Dom">
<link rel="chapter" href="zend.exception.html" title="Chapter 14. Zend_Exception">
<link rel="chapter" href="zend.feed.html" title="Chapter 15. Zend_Feed">
<link rel="chapter" href="zend.filter.html" title="Chapter 16. Zend_Filter">
<link rel="chapter" href="zend.form.html" title="Chapter 17. Zend_Form">
<link rel="chapter" href="zend.gdata.html" title="Chapter 18. Zend_Gdata">
<link rel="chapter" href="zend.http.html" title="Chapter 19. Zend_Http">
<link rel="chapter" href="zend.infocard.html" title="Chapter 20. Zend_InfoCard">
<link rel="chapter" href="zend.json.html" title="Chapter 21. Zend_Json">
<link rel="chapter" href="zend.layout.html" title="Chapter 22. Zend_Layout">
<link rel="chapter" href="zend.ldap.html" title="Chapter 23. Zend_Ldap">
<link rel="chapter" href="zend.loader.html" title="Chapter 24. Zend_Loader">
<link rel="chapter" href="zend.locale.html" title="Chapter 25. Zend_Locale">
<link rel="chapter" href="zend.log.html" title="Chapter 26. Zend_Log">
<link rel="chapter" href="zend.mail.html" title="Chapter 27. Zend_Mail">
<link rel="chapter" href="zend.measure.html" title="Chapter 28. Zend_Measure">
<link rel="chapter" href="zend.memory.html" title="Chapter 29. Zend_Memory">
<link rel="chapter" href="zend.mime.html" title="Chapter 30. Zend_Mime">
<link rel="chapter" href="zend.openid.html" title="Chapter 31. Zend_OpenId">
<link rel="chapter" href="zend.paginator.html" title="Chapter 32. Zend_Paginator">
<link rel="chapter" href="zend.pdf.html" title="Chapter 33. Zend_Pdf">
<link rel="chapter" href="zend.registry.html" title="Chapter 34. Zend_Registry">
<link rel="chapter" href="zend.rest.html" title="Chapter 35. Zend_Rest">
<link rel="chapter" href="zend.search.lucene.html" title="Chapter 36. Zend_Search_Lucene">
<link rel="chapter" href="zend.server.html" title="Chapter 37. Zend_Server">
<link rel="chapter" href="zend.service.html" title="Chapter 38. Zend_Service">
<link rel="chapter" href="zend.session.html" title="Chapter 39. Zend_Session">
<link rel="chapter" href="zend.soap.html" title="Chapter 40. Zend_Soap">
<link rel="chapter" href="zend.test.html" title="Chapter 41. Zend_Test">
<link rel="chapter" href="zend.text.html" title="Chapter 42. Zend_Text">
<link rel="chapter" href="zend.timesync.html" title="Chapter 43. Zend_TimeSync">
<link rel="chapter" href="zend.translate.html" title="Chapter 44. Zend_Translate">
<link rel="chapter" href="zend.uri.html" title="Chapter 45. Zend_Uri">
<link rel="chapter" href="zend.validate.html" title="Chapter 46. Zend_Validate">
<link rel="chapter" href="zend.version.html" title="Chapter 47. Zend_Version">
<link rel="chapter" href="zend.view.html" title="Chapter 48. Zend_View">
<link rel="chapter" href="zend.xmlrpc.html" title="Chapter 49. Zend_XmlRpc">
<link rel="appendix" href="requirements.html" title="Appendix A. Zend Framework Requirements">
<link rel="appendix" href="coding-standard.html" title="Appendix B. Zend Framework Coding Standard for PHP">
<link rel="appendix" href="copyrights.html" title="Appendix C. Copyright Information">
<link rel="index" href="the.index.html" title="Index">
<link rel="section" href="zend.locale.html#zend.locale.introduction" title="25.1. Introduction">
<link rel="section" href="zend.locale.functions.html" title="25.2. Using Zend_Locale">
<link rel="section" href="zend.locale.parsing.html" title="25.3. Normalization and Localization">
<link rel="section" href="zend.locale.date.datesandtimes.html" title="25.4. Working with Dates and Times">
<link rel="section" href="zend.locale.languages.html" title="25.5. Supported Languages for Locales">
<link rel="section" href="zend.locale.regions.html" title="25.6. Supported Regions for Locales">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader"><table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">Chapter 25. Zend_Locale</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="zend.loader.pluginloader.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="zend.locale.functions.html">Next</a>
</td>
</tr>
</table></div>
<div class="chapter" lang="en">
<div class="titlepage"><div><div><h2 class="title">
<a name="zend.locale"></a>Chapter 25. Zend_Locale</h2></div></div></div>
<div class="toc">
<p><b>Table of Contents</b></p>
<dl>
<dt><span class="sect1"><a href="zend.locale.html#zend.locale.introduction">25.1. Introduction</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.locale.html#zend.locale.whatislocalization">25.1.1. What is Localization</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.html#zend.locale.whatis">25.1.2. 
            What is a Locale?
        </a></span></dt>
<dt><span class="sect2"><a href="zend.locale.html#zend.locale.representation">25.1.3. How are Locales Represented?</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.html#zend.locale.selection">25.1.4. Selecting the Right Locale</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.html#zend.locale.selection.automatic">25.1.5. Usage of automatic Locales</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.html#zend.locale.defaultlocale">25.1.6. Using a default Locale</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.html#zend.locale.interoperate">25.1.7. ZF Locale-Aware Classes</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.html#zend.locale.formatoptions">25.1.8. Zend_Locale_Format::setOptions(array $options)</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.html#zend.locale.cache">25.1.9. Speed up Zend_Locale and it's subclasses</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="zend.locale.functions.html">25.2. Using Zend_Locale</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.locale.functions.html#zend.locale.copying">25.2.1. Copying, Cloning, and Serializing Locale Objects</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.functions.html#zend.locale.equals">25.2.2. Equality</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.functions.html#zend.locale.getdefault">25.2.3. Default locales</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.functions.html#zend.locale.setlocale">25.2.4. Set a new locale</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.functions.html#zend.locale.getlocale">25.2.5. Getting the language and region</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.functions.html#zend.locale.getdata">25.2.6. Obtaining localized strings</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.functions.html#zend.locale.getquestion">25.2.7. Obtaining translations for "yes" and "no"</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.functions.html#zend.locale.getlocalelist">25.2.8. Get a list of all known locales</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="zend.locale.parsing.html">25.3. Normalization and Localization</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.locale.parsing.html#zend.locale.number.normalize">25.3.1. Number normalization: getNumber($input, Array $options)</a></span></dt>
<dd><dl><dt><span class="sect3"><a href="zend.locale.parsing.html#zend.locale.number.normalize.precision">25.3.1.1. Precision and Calculations</a></span></dt></dl></dd>
<dt><span class="sect2"><a href="zend.locale.parsing.html#zend.locale.number.localize">25.3.2. Number localization</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.parsing.html#zend.locale.number.test">25.3.3. Number testing</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.parsing.html#zend.locale.float.normalize">25.3.4. Float value normalization</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.parsing.html#zend.locale.float.localize">25.3.5. Floating point value localization</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.parsing.html#zend.locale.float.test">25.3.6. Floating point value testing</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.parsing.html#zend.locale.integer.normalize">25.3.7. Integer value normalization</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.parsing.html#zend.locale.integer.localize">25.3.8. Integer point value localization</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.parsing.html#zend.locale.integer.test">25.3.9. Integer value testing</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.parsing.html#zend.locale.numbersystems">25.3.10. Numeral System Conversion</a></span></dt>
<dd><dl><dt><span class="sect3"><a href="zend.locale.parsing.html#zend.locale.appendix.numberscripts.supported">25.3.10.1. List of supported numeral systems</a></span></dt></dl></dd>
</dl></dd>
<dt><span class="sect1"><a href="zend.locale.date.datesandtimes.html">25.4. Working with Dates and Times</a></span></dt>
<dd><dl>
<dt><span class="sect2"><a href="zend.locale.date.datesandtimes.html#zend.locale.date.normalize">25.4.1. Normalizing Dates and Times</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.date.datesandtimes.html#zend.locale.date.test">25.4.2. Testing Dates</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.date.datesandtimes.html#zend.locale.time.normalizing">25.4.3. Normalizing a Time</a></span></dt>
<dt><span class="sect2"><a href="zend.locale.date.datesandtimes.html#zend.locale.time.test">25.4.4. Testing Times</a></span></dt>
</dl></dd>
<dt><span class="sect1"><a href="zend.locale.languages.html">25.5. Supported Languages for Locales</a></span></dt>
<dt><span class="sect1"><a href="zend.locale.regions.html">25.6. Supported Regions for Locales</a></span></dt>
</dl>
</div>
<div class="sect1" lang="en">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="zend.locale.introduction"></a>25.1. Introduction</h2></div></div></div>
<p>
        <code class="code">Zend_Locale</code> is the Frameworks answer to the question, "How can the same application be used around
        the whole world?" Most people will say, "That's easy. Let's translate all our output to several languages."
        However, using simple translation tables to map phrases from one language to another is not sufficient.
        Different regions will have different conventions for first names, surnames, salutory titles, formatting of
        numbers, dates, times, currencies, etc.
    </p>
<p>
        We need
        <a href="http://en.wikipedia.org/wiki/L10n" target="_top">Localization</a>
        and complementary
        <a href="http://en.wikipedia.org/wiki/L10n" target="_top">Internationalization</a>
        . Both are often abbreviated to <code class="code">L10n</code> and <code class="code">I18n</code>. Internationalization refers more to
        support for use of systems, regardless of special needs unique to groups of users related by language, region,
        number format conventions, financial conventions, time and date conventions, etc. Localization involves adding
        explicit support to systems for special needs of these unique groups, such as language translation, and support
        for local customs or conventions for communicating plurals, dates, times, currencies, names, symbols, sorting
        and ordering, etc. <code class="code">L10n</code> and <code class="code">I18n</code> compliment each other. The Zend Framework provides
        support for these through a combination of components, including Zend_Locale, Zend_Date, Zend_Measure,
        Zend_Translate, Zend_Currency, and Zend_TimeSync.
    </p>
<div class="tip"><table border="0" summary="Tip: Zend_Locale and setLocale()">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td>
<th align="left">Zend_Locale and setLocale()</th>
</tr>
<tr><td align="left" valign="top">
<p>
            <a href="http://php.net/setlocale" target="_top">PHP's documentation</a> states that <code class="code">setlocale()</code>
            is not threadsave because it is maintained per process and not per thread. This means that, in
            multithreaded environments, you can have the problem that the locale changes while the script
            never has changed the locale itself. This can lead to unexpected behaviour when you use
            <code class="code">setlocale()</code> in your scripts.
        </p>
<p>
            When you are using <code class="code">Zend_Locale</code> you will not have this limitations, because
            <code class="code">Zend_Locale</code> is not related to or coupled with PHP's <code class="code">setlocale()</code>.
        </p>
</td></tr>
</table></div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.locale.whatislocalization"></a>25.1.1. What is Localization</h3></div></div></div>
<p>
            Localization means that an application (or homepage) can be used from different users which speak different
            languages. But as you already have expected Localization means more than only translating strings. It
            includes
        </p>
<div class="itemizedlist"><ul type="opencircle">
<li style="list-style-type: circle"><p>
                    <code class="code">Zend_Locale</code> - Backend support of locales available for localization support within
                    other ZF components.
                </p></li>
<li style="list-style-type: circle"><p>
                    <code class="code">Zend_Translate</code> - Translating of strings.
                </p></li>
<li style="list-style-type: circle"><p>
                    <code class="code">Zend_Date</code> - Localization of dates, times.
                </p></li>
<li style="list-style-type: circle"><p>
                    <code class="code">Zend_Calendar</code> - Localization of calendars (support for non-Gregorian calendar systems)
                </p></li>
<li style="list-style-type: circle"><p>
                    <code class="code">Zend_Currency</code> - Localization of currencies.
                </p></li>
<li style="list-style-type: circle"><p>
                    <code class="code">Zend_Locale_Format</code> - Parsing and generating localized numbers.
                </p></li>
<li style="list-style-type: circle"><p>
                    <code class="code">Zend_Locale_Data</code> - Retrieve localized standard strings as country names, language names
                    and
                    <a href="http://unicode.org/cldr/" target="_top">more from the CLDR</a>
                    .
                </p></li>
<li style="list-style-type: circle"><p>
                    <code class="code">TODO</code> - Localization of collations
                </p></li>
</ul></div>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.locale.whatis"></a>25.1.2. 
            <a href="http://unicode.org/reports/tr35/#Locale" target="_top">What is a Locale?</a>
        </h3></div></div></div>
<p>
            Each computer user makes use of Locales, even when they don't know it. Applications lacking localization
            support, normally have implicit support for one particular locale (the locale of the author). When a class
            or function makes use of localization, we say it is <code class="code">locale-aware</code>. How does the code know which
            localization the user is expecting?
        </p>
<p>
            A locale string or object identifying a supported locale gives <code class="code">Zend_Locale</code> and it's subclasses
            access to information about the language and region expected by the user. Correct formatting, normalization,
            and conversions are made based on this information.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.locale.representation"></a>25.1.3. How are Locales Represented?</h3></div></div></div>
<p>
            Locale identifiers consist of information about the user's language and preferred/primary geographic region
            (e.g. state or province of home or workplace). The locale identifier strings used in the Zend Framework are
            internationally defined standard abbreviations of language and region, written as
            <code class="code">language_REGION</code>. Both the language and region parts are abbreviated to alphabetic, ASCII
            characters.
        </p>
<div class="note"><table border="0" summary="Note">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.png"></td>
<th align="left">Note</th>
</tr>
<tr><td align="left" valign="top"><p>
                Be aware that there exist not only locales with 2 characters as most people think. Also there
                are languages and regions which are not only abbreviated with 2 characters. Therefor you should
                NOT strip the region and language yourself, but use Zend_Locale when you want to strip language
                or region from a locale string. Otherwise you could have unexpected behaviour within your code
                when you do this yourself.
            </p></td></tr>
</table></div>
<p>
            A user from USA would expect the language <code class="code">English</code> and the region <code class="code">USA</code>, yielding the
            locale identifier "en_US". A user in Germany would expect the language <code class="code">German</code> and the region
            <code class="code">Germany</code>, yielding the locale identifier "de_DE". See the
            <a href="http://unicode.org/cldr/data/diff/supplemental/languages_and_territories.html" target="_top">list of pre-defined locale and region combinations</a>
            , if you need to select a specific locale within the Zend Framework.
        </p>
<div class="example">
<a name="zend.locale.representation.example-1"></a><p class="title"><b>Example 25.1. Choosing a specific locale</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
require_once 'Zend/Locale.php';
$locale = new Zend_Locale('de_DE'); // German language _ Germany
            </pre></div>
</div>
<br class="example-break"><p>
            A German user in America might expect the language <code class="code">German</code> and the region <code class="code">USA</code>, but
            these non-standard mixes are not supported directly as recognized "locales". Instead, if an invalid
            combination is used, then it will automatically be truncated by dropping the region code. For example,
            "de_IS" would be truncated to "de", and "xh_RU" would be truncated to "xh", because neither of these
            combinations are valid. Additionally, if the base language code is not supported (e.g. "zz_US") or does not
            exist, then a default "root" locale will be used. The "root" locale has default definitions for
            internationally recognized representations of dates, times, numbers, currencies, etc. The truncation process
            depends on the requested information, since some combinations of language and region might be valid for one
            type of data (e.g. dates), but not for another (e.g. currency format).
        </p>
<p>
            Beware of historical changes, as ZF components do not know about or attempt to track the numerous timezone
            changes made over many years by many regions. For example,
            <a href="http://www.statoids.com/tus.html" target="_top">we can see a historical list</a>
            showing dozens of changes made by governments to when and if a particular region observes Daylight Savings
            Time, and even which timezone a particular geographic area belongs. Thus, when performing date math, the
            math performed by ZF components will not adjust for these changes, but instead will give the correct time
            for the timezone using current, modern rules for DST and timezone assignment for geographic regions.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.locale.selection"></a>25.1.4. Selecting the Right Locale</h3></div></div></div>
<p>
            For most situations, <code class="code">new Zend_Locale()</code> will automatically select the correct locale, with
            preference given to information provided by the user's web browser. However, if <code class="code">new
            Zend_Locale(Zend_Locale::ENVIRONMENT)</code> is used, then preference will be given to using the host
            server's environment configuration, as described below.
        </p>
<div class="example">
<a name="zend.locale.selection.example-1"></a><p class="title"><b>Example 25.2. Automatically selecting a locale</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
require_once 'Zend/Locale.php';
$locale  = new Zend_Locale();
$locale1 = new Zend_Locale(Zend_Locale::BROWSER);     // default behavior, same as above
$locale2 = new Zend_Locale(Zend_Locale::ENVIRONMENT); // prefer settings on host server
$locale3 = new Zend_Locale(Zend_Locale::FRAMEWORK);   // perfer framework app default settings
            </pre></div>
</div>
<br class="example-break"><p>
            The seach algorithm used by <code class="code">Zend_Locale</code> for automatic selection of a locale uses three sources
            of information:
            </p>
<div class="orderedlist"><ol type="1">
<li><p>
                        const <code class="code">Zend_Locale::BROWSER</code> - The user's Web browser provides information with each
                        request, which is published by PHP in the global variable <code class="code">HTTP_ACCEPT_LANGUAGE</code>. If
                        no matching locale can be found, then preference is given to <code class="code">ENVIRONMENT</code> and lastly
                        <code class="code">FRAMEWORK</code>.
                    </p></li>
<li><p>
                        const <code class="code">Zend_Locale::ENVIRONMENT</code> - PHP publishes the host server's locale via the PHP
                        internal function <code class="code">setlocale()</code>. If no matching locale can be found, then preference
                        is given to FRAMEWORK and lastly BROWSER.
                    </p></li>
<li><p>
                        const <code class="code">Zend_Locale::FRAMEWORK</code> - When the Zend Framework has a standardized way of
                        specifying component defaults (planned, but not yet available), then using this constant during
                        instantiation will give preference to choosing a locale based on these defaults. If no matching
                        locale can be found, then preference is given to <code class="code">ENVIRONMENT</code> and lastly
                        <code class="code">BROWSER</code>.
                    </p></li>
</ol></div>
<p>
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.locale.selection.automatic"></a>25.1.5. Usage of automatic Locales</h3></div></div></div>
<p>
            <code class="code">Zend_Locale</code> provides three additionally locales. These locales do not belong to
            any language or region. They are "automatic" locales which means that they have the same effect
            as the method <code class="code">getDefault()</code> but without the negative effects like creating an instance. 
            These "automatic" locales can be used anywhere, where also a standard locale and also the
            definition of a locale, it's string representation, can be used. This offers simplicity for
            situations like working with locales which are provided by a browser.
        </p>
<p>
            There are three locales which have a slightly different behaviour:

            </p>
<div class="orderedlist"><ol type="1">
<li>
<p>
                        <code class="code">'browser'</code> - <code class="code">Zend_Locale</code> should work with the information
                        which is provided by the user's Web browser. It is published by PHP in the global
                        variable <code class="code">HTTP_ACCEPT_LANGUAGE</code>.
                    </p>
<p>
                        If a user provides more than one locale within his browser, <code class="code">Zend_Locale</code>
                        will use the first found locale. If the user does not provide a locale or the script is
                        being called from the commandline the automatic locale <code class="code">'environment'</code>
                        will automatically be used and returned.
                    </p>
</li>
<li>
<p>
                        <code class="code">'environment'</code> - <code class="code">Zend_Locale</code> should work with the information
                        which is provided by the host server. It is published by PHP via the internal function
                        <code class="code">setlocale()</code>.
                    </p>
<p>
                        If a environment provides more than one locale, <code class="code">Zend_Locale</code> will use the
                        first found locale. If the host does not provide a locale the automatic locale
                        <code class="code">'browser'</code> will automatically be used and returned.
                    </p>
</li>
<li>
<p>
                        <code class="code">'auto'</code> - <code class="code">Zend_Locale</code> should automatically detect any locale
                        which can be worked with. It will first search for a users locale and then, if not
                        successfull, search for the host locale.
                    </p>
<p>
                        If no locale can be detected, it will throw an exception and tell you that the
                        automatical detection has been failed.
                    </p>
</li>
</ol></div>
<p>
        </p>
<div class="example">
<a name="zend.locale.selection.automatic.example-1"></a><p class="title"><b>Example 25.3. Using automatic locales</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
require_once 'Zend/Locale.php';
require_once 'Zend/Date.php';

// without automatic detection
//$locale = new Zend_Locale(Zend_Locale::BROWSER);
//$date = new Zend_Date($locale);

// with automatic detection
$date = new Zend_Date('auto');
            </pre></div>
</div>
<br class="example-break">
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.locale.defaultlocale"></a>25.1.6. Using a default Locale</h3></div></div></div>
<p>
            In some environments it is not possible to detect a locale automatically. You can expect this
            behaviour when you get an request from commandline or the requesting browser has no language tag
            set and additionally your server has the default locale 'C' set or another properitary locale.
        </p>
<p>
            In such cases <code class="code">Zend_Locale</code> will normally throw an exception with a message that
            the automatic detection of any locale was not successfull. You have two options to handle such
            a situation. Either through setting a new locale per hand, or defining a default locale.
        </p>
<div class="example">
<a name="zend.locale.defaultlocale.example-1"></a><p class="title"><b>Example 25.4. Handling locale exceptions</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
// within the bootstrap file
require_once 'Zend/Locale.php';

try {
    $locale = new Zend_Locale('auto');
} catch (Zend_Locale_Exception $e) {
    $locale = new Zend_Locale('de');
}

// within your model/controller
$date = new Zend_Date($locale);
            </pre></div>
</div>
<br class="example-break"><p>
            But this has one big negative effect. You will have to set your locale object within
            every class using <code class="code">Zend_Locale</code>. This could become very unhandy if you are using
            multiple classes.
        </p>
<p>
            Since Zend Framework Release 1.5 there is a much better way to handle this. You can set a
            default locale which the static <code class="code">setDefault()</code> method. Of course, every unknown
            or not full qualified locale will also throw an exception. <code class="code">setDefault()</code> should
            be the first call before you initiate any class using <code class="code">Zend_Locale</code>. See the
            following example for details:
        </p>
<div class="example">
<a name="zend.locale.defaultlocale.example-2"></a><p class="title"><b>Example 25.5. Setting a default locale</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
// within the bootstrap file
require_once 'Zend/Locale.php';

Zend_Locale::setDefault('de');

// within your model/controller
$date = new Zend_Date();
            </pre></div>
</div>
<br class="example-break"><p>
            In the case that no locale can be detected, automatically the locale
            <span class="strong"><strong>de</strong></span> will be used. Otherwise, the detected locale will be used.
        </p>
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.locale.interoperate"></a>25.1.7. ZF Locale-Aware Classes</h3></div></div></div>
<p>
            In the ZF, locale-aware classes rely on <code class="code">Zend_Locale</code> to automatically select a locale, as
            explained above. For example, in a ZF web application, constructing a date using <code class="code">Zend_Date</code>
            without specifying a locale results in an object with a locale based on information provided by the current
            user's web browser.
        </p>
<div class="example">
<a name="zend.locale.interoperate.example-1"></a><p class="title"><b>Example 25.6. Dates default to correct locale of web users</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
require_once 'Zend/Date.php';
$date = new Zend_Date('2006',Zend_Date::YEAR);
            </pre></div>
</div>
<br class="example-break"><p>
            To override this default behavior, and force locale-aware ZF components to use specific locales, regardless
            of the origin of your website visitors, explicitly specify a locale as the third argument to the
            constructor.
        </p>
<div class="example">
<a name="zend.locale.interoperate.example-2"></a><p class="title"><b>Example 25.7. Overriding default locale selection</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
require_once 'Zend/Date.php';
require_once 'Zend/Measure/Temperature.php';

$usLocale = new Zend_Locale('en_US');
$date = new Zend_Date('2006', Zend_Date::YEAR, $usLocale);
$temp = new Zend_Measure_Temperature('100,10', Zend_Measure::TEMPERATURE, $usLocale);
            </pre></div>
</div>
<br class="example-break"><p>
            If you know many objects should all use the same default locale, explicitly specify the default locale to
            avoid the overhead of each object determining the default locale.
        </p>
<div class="example">
<a name="zend.locale.interoperate.example-3"></a><p class="title"><b>Example 25.8. Performance optimization when using a default locale</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
require_once 'Zend/Date.php';
require_once 'Zend/Measure/Temperature.php';

$locale = new Zend_Locale();
$date = new Zend_Date('2006', Zend_Date::YEAR, $locale);
$temp = new Zend_Measure_Temperature('100,10', Zend_Measure::TEMPERATURE, $locale);
            </pre></div>
</div>
<br class="example-break">
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.locale.formatoptions"></a>25.1.8. Zend_Locale_Format::setOptions(array $options)</h3></div></div></div>
<p>
            The 'precision' option of a value is used to truncate or stretch extra digits. A value of '-1' disables
            modification of the number of digits in the fractional part of the value. The 'locale' option helps when
            parsing numbers and dates using separators and month names. The date format 'format_type' option selects between
            CLDR/ISO date format specifier tokens and PHP's date() tokens. The 'fix_date' option enables or disables
            heuristics that attempt to correct invalid dates. The 'number_format' option specifies a default number
            format for use with <code class="code">toNumber()</code> (see
            <a href="zend.locale.parsing.html#zend.locale.number.localize" title="25.3.2. Number localization">Section 25.3.2, “Number localization”</a>
            ).
        </p>
<p>
            The 'date_format' option can be used to specify a default date format string, but beware of using getDate(),
            checkdateFormat() and getTime() after using setOptions() with a 'date_format'. To use these four methods
            with the default date format for a locale, use array('date_format' =&gt; null, 'locale' =&gt; $locale) for their
            options.
        </p>
<div class="example">
<a name="zend.locale.formatoptions.example-1"></a><p class="title"><b>Example 25.9. Dates default to correct locale of web users</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
require_once 'Zend/Locale.php';
Zend_Locale_Format::setOptions(array('locale' =&gt; 'en_US', 'fix_date' =&gt; true, 'format_type' =&gt; 'php'));
            </pre></div>
</div>
<br class="example-break"><p>
            For working with the standard definitions of a locale the option Zend_Locale_Format::STANDARD can be used.
            Setting the option Zend_Locale_Format::STANDARD for date_format uses the standard definitions from the actual
            set locale. Setting it for number_format uses the standard number format for this locale.
            And setting it for locale uses the standard locale for this environment or browser.
        </p>
<div class="example">
<a name="zend.locale.formatoptions.example-2"></a><p class="title"><b>Example 25.10. Using STANDARD definitions for setOptions()</b></p>
<div class="example-contents"><pre class="programlisting">&lt;?php
require_once 'Zend/Locale.php';
Zend_Locale_Format::setOptions(array('locale' =&gt; 'en_US', 'date_format' =&gt; 'dd.MMMM.YYYY'));
// overriding the global set date format
$date = Zend_Locale_Format::getDate('2007-04-20, array('date_format' =&gt; Zend_Locale_Format::STANDARD);

// global setting of the standard locale
Zend_Locale_Format::setOptions(array('locale' =&gt; Zend_Locale_Format::STANDARD, 'date_format' =&gt; 'dd.MMMM.YYYY'));
            </pre></div>
</div>
<br class="example-break">
</div>
<div class="sect2" lang="en">
<div class="titlepage"><div><div><h3 class="title">
<a name="zend.locale.cache"></a>25.1.9. Speed up Zend_Locale and it's subclasses</h3></div></div></div>
<p>
            <code class="code">Zend_Locale</code> and it's subclasses can be speed up by the usage of <code class="code">Zend_Cache</code>.
            Use the static method <code class="code">Zend_Locale::setCache($cache)</code> if you are using
            <code class="code">Zend_Locale</code>. <code class="code">Zend_Locale_Format</code> can be speed up the using the option
            <code class="code">cache</code> within <code class="code">Zend_Locale_Format::setOptions(array('cache' =&gt; $adapter));</code>.
            If you are using both classes you should only set the cache for <code class="code">Zend_Locale</code>, otherwise
            the last set cache will overwrite the previous set cache. For convenience there is also static method
            <code class="code">Zend_Locale::getCache()</code>.
        </p>
</div>
</div>
</div>
<div class="navfooter"><table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="zend.loader.pluginloader.html">Prev</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="zend.locale.functions.html">Next</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">24.2. Loading Plugins </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td>
<td width="40%" align="right" valign="top"> 25.2. Using Zend_Locale</td>
</tr>
</table></div>
<div class="revinfo"></div>
</body>
</html>
